koa-send

What is koa-send?

The koa-send package is a utility for Koa applications that allows you to serve static files. It is commonly used to serve files such as HTML, CSS, JavaScript, images, and other static assets from a directory on the server.

What are koa-send's main functionalities?

Serving Static Files

This feature allows you to serve static files from a specified path. In this example, when a request is made to '/static', the server responds with the file located at 'path/to/static/file.html'.

const Koa = require('koa');
const send = require('koa-send');
const app = new Koa();

app.use(async (ctx) => {
  if (ctx.path === '/static') {
    await send(ctx, 'path/to/static/file.html');
  }
});

app.listen(3000);

Serving Files from a Directory

This feature allows you to serve files from a directory. In this example, any request path will be mapped to a file in the 'public' directory relative to the current directory.

const Koa = require('koa');
const send = require('koa-send');
const app = new Koa();

app.use(async (ctx) => {
  await send(ctx, ctx.path, { root: __dirname + '/public' });
});

app.listen(3000);

Setting Cache Control Headers

This feature allows you to set cache control headers for the served files. In this example, the 'maxage' option is set to 1 hour, which will set the 'Cache-Control' header to cache the file for 1 hour.

const Koa = require('koa');
const send = require('koa-send');
const app = new Koa();

app.use(async (ctx) => {
  await send(ctx, 'path/to/static/file.html', { maxage: 1000 * 60 * 60 }); // 1 hour
});

app.listen(3000);

Other packages similar to koa-send

koa-static

koa-static is another middleware for serving static files in a Koa application. It is similar to koa-send but is more focused on serving static files from a directory. It provides a simpler API for serving static files and is often used in conjunction with other Koa middlewares.

serve-static

serve-static is a middleware for serving static files in Express applications, but it can also be used with Koa through the koa-connect package. It provides similar functionality to koa-send, allowing you to serve static files from a directory with options for caching and other settings.

koa-static-cache

koa-static-cache is a Koa middleware for serving static files with caching capabilities. It is similar to koa-send but includes built-in support for caching files in memory, which can improve performance for frequently accessed files.

README

koa-send

Static file serving middleware.

Installation

$ npm install koa-send

Options

• maxage Browser cache max-age in milliseconds. (defaults to 0)
• hidden Allow transfer of hidden files. (defaults to false)
• root Root directory to restrict file access
• gzip Try to serve the gzipped version of a file automatically when gzip is supported by a client and if the requested file with .gz extension exists. defaults to true.
• format If not false (defaults to true), format the path to serve static file servers and not require a trailing slash for directories, so that you can do both /directory and /directory/
• setHeaders Function to set custom headers on response.
• extensions Try to match extensions from passed array to search for file when no extension is sufficed in URL. First found is served. (defaults to false)

Root path

Note that root is required, defaults to '' and will be resolved, removing the leading / to make the path relative and this path must not contain "..", protecting developers from concatenating user input. If you plan on serving files based on user input supply a root directory from which to serve from.

For example to serve files from ./public:

app.use(function *(){
  yield send(this, this.path, { root: __dirname + '/public' });
})

To serve developer specified files:

app.use(function *(){
  yield send(this, 'path/to/my.js');
})

setHeaders

The function is called as fn(res, path, stats), where the arguments are:

• res: the response object
• path: the resolved file path that is being sent
• stats: the stats object of the file that is being sent.

You should only use the setHeaders option when you wish to edit the Cache-Control or Last-Modified headers, because doing it before is useless (it's overwritten by send), and doing it after is too late because the headers are already sent.

If you want to edit any other header, simply set them before calling send.

Example (Koa@2) with async/await

var send = require('koa-send');
var Koa = require('koa');
var app = new Koa();

// $ GET /package.json
// $ GET /

app.use(async function (ctx, next){
  if ('/' == ctx.path) return ctx.body = 'Try GET /package.json';
  await send(ctx, ctx.path);
})

app.listen(3000);
console.log('listening on port 3000');

Example

var send = require('koa-send');
var koa = require('koa');
var app = koa();

// $ GET /package.json
// $ GET /

app.use(function *(){
  if ('/' == this.path) return this.body = 'Try GET /package.json';
  yield send(this, this.path);
})

app.listen(3000);
console.log('listening on port 3000');

License

MIT